/**
 *******************************************************************************
 *                       Continental Confidential
 *                  Copyright (c) Continental AG. 2017
 *
 *      This software is furnished under license and may be used or
 *      copied only in accordance with the terms of such license.
 *******************************************************************************
 * @file    plugininterface.h
 * @brief   插件接口基类头文件
 * @note    中文注释：定义所有插件必须实现的接口规范，包含插件元数据和界面管理
 *          English: Header file for plugin interface base class, defining interface specifications for all plugins
 *******************************************************************************
 */
#ifndef PLUGININTERFACE_H
#define PLUGININTERFACE_H

#include "plugininterface_global.h"
#include <QObject>
#include <QMimeData>

/**
 * @brief 字节数组MIME类型字符串
 * @details 用于标识字节数组类型的MIME数据，对应MIMEDATA_BYTEARRAY枚举值
 */
#define MIMEDATA_BYTEARRAY_STRING "bytearray"

/**
 * @brief 文本MIME类型字符串
 * @details 用于标识纯文本类型的MIME数据，对应MIMEDATA_TEXT枚举值
 */
#define MIMEDATA_TEXT_STRING "text/plain"

/**
 * @brief HTMLMIME类型字符串
 * @details 用于标识HTML格式的MIME数据，对应MIMEDATA_HTML枚举值
 */
#define MIMEDATA_HTML_STRING "text/html"

/**
 * @brief URLMIME类型字符串
 * @details 用于标识URL链接的MIME数据，对应MIMEDATA_URL枚举值
 */
#define MIMEDATA_URL_STRING "text/uri-list"

/**
 * @brief 图像MIME类型字符串
 * @details 用于标识图像类型的MIME数据，对应MIMEDATA_IMAGE枚举值
 */
#define MIMEDATA_IMAGE_STRING "image/ *"

/**
 * @brief 颜色MIME类型字符串
 * @details 用于标识颜色类型的MIME数据，对应MIMEDATA_COLOR枚举值
 */
#define MIMEDATA_COLOR_STRING "application/x-color"


/**
 * @enum MIMEDATA_TYPE
 * @brief MIME数据类型枚举
 * @details 定义插件间数据交换支持的MIME数据格式类型，用于标准化插件间的数据传输格式
 *          每个枚举值对应一种Qt支持的MIME类型，方便插件间识别和处理数据
 */
enum class MIMEDATA_TYPE: uint
{
    MIMEDATA_BYTEARRAY=100, ///< 字节数组类型数据，用于传输二进制数据或自定义格式数据
    MIMEDATA_TEXT,          ///< 文本类型数据，对应"text/plain"格式
    MIMEDATA_HTML,          ///< HTML格式数据，对应"text/html"格式
    MIMEDATA_URL,           ///< URL链接数据，对应"text/uri-list"格式
    MIMEDATA_IMAGE,         ///< 图像数据，支持各种图像格式
    MIMEDATA_COLOR          ///< 颜色数据，对应"application/x-color"格式
}; // TODO: Qt5.15.2升级 - 使用Q_ENUM_NS宏使枚举可在元对象系统中使用（需包含QObject头文件）
Q_DECLARE_METATYPE(MIMEDATA_TYPE) // 声明为元类型，支持在信号槽中传递
// TODO: Qt5.15.2升级 - 考虑使用Q_DECLARE_OPAQUE_POINTER宏为复杂类型提供更好的支持

/**
 * @class PluginInterFace
 * @brief 插件接口基类
 * @details 所有插件必须实现的抽象接口类，定义插件与应用程序及其他插件交互的标准接口
 *          提供插件名称管理、界面组件获取和MIME数据交换等核心功能
 *          继承自QObject以支持Qt的信号槽机制和元对象系统
 */
class PLUGININTERFACESHARED_EXPORT PluginInterFace : public QObject
{
    Q_OBJECT
public:
    /**
     * @brief 构造函数
     * @param parent 父对象指针，默认为nullptr
     * @details 初始化MIME数据对象和插件名称，设置父对象关系
     *          为插件提供基本的Qt对象生命周期管理
     */
    PluginInterFace(QObject *parent=nullptr); // TODO: Qt5.15.2升级 - 已使用nullptr替代0作为默认参数
                                             // TODO: C++17升级 - 考虑添加constexpr构造函数
    
    /**
     * @brief 析构函数
     * @details 虚析构函数，确保子类资源在对象销毁时正确释放
     *          基类析构函数负责清理基类分配的资源
     */
    virtual ~PluginInterFace(); // TODO: C++17升级 - 考虑添加override关键字和noexcept规范
    
    /**
     * @brief 获取插件名称
     * @return 插件名称字符串常量引用
     * @details 纯虚函数，子类必须实现以返回唯一标识插件的名称
     *          该名称用于在应用程序中识别和管理插件
     */
    virtual const QString &getPluginName() const = 0;
    
    /**
     * @brief 设置插件名称
     * @param pluginName 要设置的插件名称
     * @details 纯虚函数，子类必须实现以设置插件的唯一标识名称
     *          通常在插件加载时由应用程序调用
     */
    virtual void setPluginName(const QString &pluginName) = 0;
    
    /**
     * @brief 获取插件界面组件
     * @return 插件主界面窗口部件指针
     * @details 纯虚函数，子类实现以提供插件的可视化界面组件
     *          应用程序将此部件集成到主界面中显示
     */
    virtual QWidget * getWidget() const = 0;
    
    /**
     * @brief 获取MIME数据
     * @return MIME数据对象常量引用
     * @details 返回插件当前的MIME数据，用于插件间的数据交换
     *          其他插件或应用程序可以通过此方法获取本插件提供的数据
     */
    virtual const QMimeData &getMineData() const = 0;
    
    /**
     * @brief 设置MIME数据
     * @param mimetype MIME数据类型，指定要设置的数据格式
     * @param data 要设置的数据，以QVariant类型包装
     * @details 纯虚函数，子类实现以支持接收和处理特定类型的MIME数据
     *          其他插件或应用程序可以通过此方法向本插件发送数据
     */
    virtual void setMimeData(const MIMEDATA_TYPE &mimetype, const QVariant &data) = 0;

protected:
    QMimeData m_mineData;   ///< MIME数据存储对象，用于保存插件的输入/输出数据
                            ///< 插件间通过此对象交换各种类型的数据
    QString m_pluginName;   ///< 插件名称存储，保存插件的唯一标识名称
                            ///< 应用程序使用此名称识别和管理不同的插件
    // TODO: C++17升级 - 考虑使用std::string_view替代QString以提高性能（如适用）

};

#endif // PLUGININTERFACE_H
